home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / WINDOWS / MDIT.ARJ / PCTHREAD.H < prev    next >
C/C++ Source or Header  |  1992-03-30  |  10KB  |  414 lines
  1. /****************************************************************
  2.  *  (C)  The TriTechnology Company, 1991                        *
  3.  *       Bellevue, Wa.  98005                                         *
  4.  *                                                                    *
  5.  *       This software is furnished under a license and may     *
  6.  *       be used and copied only in accordance with the terms   *
  7.  *       of such license and with the inclusion of the above    *
  8.  *       copyright notice.  this software or any other copies   *
  9.  *       thereof may not be provided or otherwise made avail-   *
  10.  *       able to any other person.  No title to and ownership   *
  11.  *       of the software is hereby transferred.                 *
  12.  *                                                              *
  13.  *       The information in this software is subject to change  *
  14.  *       without notice and should not be construed as a        *
  15.  *       commitment by The TriTechnology Company.               *
  16.  ****************************************************************
  17.  *
  18.  * Facility:
  19.  *
  20.  *     pcthread.h
  21.  *
  22.  * Abstract:
  23.  *
  24.  *       PCthreads(tm) Application Programming Interface, API.
  25.  *       The functions declared in this header file may be called
  26.  *       by application programs (aka client applications) whose 
  27.  *       design requires multiple threads of execution.  These 
  28.  *       functions provide a complete set of primitives necessary
  29.  *       for the creation, run-time management, and deletion of
  30.  *       threads, mutexes, and condition variables.  Moreover, 
  31.  *       these routines are all that are required to design higher
  32.  *       level abstractions, such as monitors, counting sema-
  33.  *       phores, friendly mutexes, etc,.
  34.  *
  35.  */
  36.  
  37. #ifndef _PCTHREAD_H
  38. #define _PCTHREAD_H
  39.  
  40. #include "typedefs.h"
  41. #include "except.h"
  42.  
  43. /*
  44.  *  --   Clients may initialize the Run-Time Management System, RTMS using
  45.  *       their own settings.  This is not a required service.  For it to 
  46.  *       have any effect it must be the very first service called.
  47.  */
  48.  
  49. int 
  50. pcthread_attr_setdefaults_np( policy_t   scheduling_policy,
  51.                               unsigned   thread_quantum,
  52.                               int        max_thread_priority,
  53.                               int        default_thread_priority,
  54.                               unsigned   default_thread_stack_size,
  55.                               boolean_t  thread_inheritance );
  56.  
  57.  
  58.  
  59.  
  60.  
  61. /*
  62.  *  --   Thread attributes object services.
  63.  */
  64.  
  65. int 
  66. pcthread_attr_create( pcthread_attr_t *th_attr );
  67.  
  68. int 
  69. pcthread_attr_delete( pcthread_attr_t *th_attr );
  70.  
  71. int 
  72. pcthread_attr_setprio( pcthread_attr_t *th_attr, int prio );
  73.  
  74. int 
  75. pcthread_attr_getprio( pcthread_attr_t th_attr );
  76.  
  77. int 
  78. pcthread_attr_setsched( pcthread_attr_t *th_attr, int policy );
  79.  
  80. int 
  81. pcthread_attr_getsched( pcthread_attr_t th_attr );
  82.  
  83. int 
  84. pcthread_attr_setinheritsched( pcthread_attr_t *attr, int inherit );
  85.  
  86. int 
  87. pcthread_attr_getinheritsched( pcthread_attr_t th_attr );
  88.  
  89. int 
  90. pcthread_attr_setstacksize( pcthread_attr_t *attr, int stacksize );
  91.  
  92. int 
  93. pcthread_attr_getstacksize( pcthread_attr_t th_attr );
  94.  
  95. int 
  96. pcthread_attr_getmaxprio_np( void );
  97.  
  98. int 
  99. pcthread_attr_setquantum_np( pcthread_attr_t *attr, int quantum );
  100.  
  101. int 
  102. pcthread_attr_getquantum_np( pcthread_attr_t th_attr );
  103.  
  104. pcthread_attr_t * 
  105. pcthread_attr_default_np( void );
  106.  
  107. /*
  108.  *  --   Allow client threads to operate on mutex attributes objects.
  109.  */
  110.  
  111. int 
  112. pcthread_mutexattr_create( pcthread_mutexattr_t *mu_attr );
  113.  
  114. int 
  115. pcthread_mutexattr_delete( pcthread_mutexattr_t *mu_attr );
  116.  
  117. int 
  118. pcthread_mutexattr_setprotocol(pcthread_mutexattr_t *attr, sched_protocol_t p);
  119.  
  120.  
  121. int 
  122. pcthread_mutexattr_getprotocol( pcthread_mutexattr_t mu_attr );
  123.  
  124. pcthread_mutexattr_t *
  125. pcthread_mutexattr_default_np( void );
  126.  
  127. /*
  128.  *  --   Allow threads to operate on condition variable attributes objects.
  129.  */
  130.  
  131. int 
  132. pcthread_condattr_create( pcthread_condattr_t *cv_attr );
  133.  
  134. int 
  135. pcthread_condattr_delete( pcthread_condattr_t *cv_attr );
  136.  
  137. pcthread_condattr_t * 
  138. pcthread_condattr_default_np( void );
  139.  
  140. /*  
  141.  *  --   Thread-specific services.  First, thread creation
  142.  */
  143.  
  144. int 
  145. pcthread_create(   pcthread_t *th_handle,
  146.                    pcthread_attr_t th_attr,
  147.                    pcthread_action_t action,
  148.                    pcthread_addr_t *argument    );
  149.  
  150. /*  
  151.  *  -- A thread may wait for the completion of another and obtain the return
  152.  *     value of its action routine, if any.
  153.  */
  154.  
  155. int 
  156. pcthread_join( pcthread_t th_handle, pcthread_addr_t *status );
  157.  
  158. /*
  159.  *  --   A thread may terminate itself and pass a status value back to any 
  160.  *       thread that is waiting for it to complete (i.e., via the
  161.  *       pcthread_join() service ).
  162.  */
  163.  
  164. void 
  165. pcthread_exit( pcthread_addr_t status );
  166.  
  167. /*
  168.  *  --   A thread may use pcthread_detach() to indicate to the run time system
  169.  *       that its resources (e.g., memory) may be reclaimed upon termination.
  170.  *       This does not cause the thread to terminate, but does preclude any
  171.  *       threads from joining with it, once pcthread_detach() has been called.
  172.  */
  173.  
  174. int 
  175. pcthread_detach( pcthread_t *th_handle );
  176.  
  177.  
  178.  
  179.  
  180.  
  181. /*  
  182.  *  --   Client applications may adjust a thread's priority    
  183.  */
  184.  
  185. int 
  186. pcthread_setprio( pcthread_t *th_handle, int priority );
  187.  
  188. int 
  189. pcthread_getprio( pcthread_t *th_handle );
  190.  
  191. int 
  192. pcthread_setactive_prio_np( int p );
  193.  
  194. int 
  195. pcthread_getactive_prio_np( void );
  196.  
  197. int 
  198. pcthread_setscheduler( pcthread_t *th_handle, int policy, int priority );
  199.  
  200. int 
  201. pcthread_getscheduler( pcthread_t th_handle );
  202.  
  203. int 
  204. pcthread_setattr( pcthread_t th_handle, pcthread_attr_t attr );
  205.  
  206. int 
  207. pcthread_getattr( pcthread_t th_handle, pcthread_attr_t *attr );
  208.  
  209. /* 
  210.  *  -- Client threads may obtain their own handles
  211.  */
  212.  
  213. pcthread_t * 
  214. pcthread_self( void );
  215.  
  216. /* 
  217.  *  -- Client threads may unconditionally yield the processor.
  218.  */
  219.  
  220. void 
  221. pcthread_yield( void );
  222.  
  223. /* 
  224.  *  -- Client threads may execute a timed delay until a specified time, or
  225.  *     for a specified interval of time.
  226.  */
  227.  
  228. void 
  229. pcthread_delay_absolute_np( timespec_t *abstime );
  230.  
  231. void 
  232. pcthread_delay_relative_np( timespec_t *time_delay );
  233.  
  234. /*
  235.  *  --   Client applications may test two threads for equality
  236.  */
  237.  
  238. int 
  239. pcthread_equal( pcthread_t th1_handle, pcthread_t th2_handle );
  240.  
  241. /*
  242.  *  -- Mutex services
  243.  */
  244.  
  245. int 
  246. pcthread_mutex_init( pcthread_mutex_t *mutex, pcthread_mutexattr_t mu_attr );
  247.  
  248. int 
  249. pcthread_mutex_destroy( pcthread_mutex_t *mu_handle );
  250.  
  251. int 
  252. pcthread_mutex_blockedthreads_np( pcthread_mutex_t *mu_handle );
  253.  
  254. int 
  255. pcthread_mutex_lock( pcthread_mutex_t *mu_handle );
  256.  
  257. int 
  258. pcthread_mutex_unlock( pcthread_mutex_t *mu_handle );
  259.  
  260. int 
  261. pcthread_mutex_trylock( pcthread_mutex_t *mu_handle );
  262.  
  263. /*
  264.  *  --   Condition variable services
  265.  */
  266.  
  267. int 
  268. pcthread_cond_init( pcthread_cond_t *cv, pcthread_condattr_t cv_attr );
  269.  
  270. int 
  271. pcthread_cond_destroy( pcthread_cond_t *cv_handle );
  272.  
  273. int 
  274. pcthread_cond_waitingthreads_np( pcthread_cond_t *cv_handle );
  275.  
  276. int 
  277. pcthread_cond_wait( pcthread_cond_t *cv,  pcthread_mutex_t *mutex );
  278.  
  279. int 
  280. pcthread_cond_timedwait( pcthread_t *cv, pcthread_mutex_t *mu, timespec_t *t );
  281.  
  282. int 
  283. pcthread_cond_signal( pcthread_cond_t *cv_handle );
  284.  
  285. int 
  286. pcthread_cond_broadcast( pcthread_cond_t *cv_handle );
  287.  
  288. /* 
  289.  *  --   Disable and Enable asynchronous (aka clock-mediated) preemption
  290.  */
  291.  
  292. int 
  293. pcthread_disable_preemption_np( void );
  294.  
  295. void 
  296. pcthread_enable_preemption_np( int );
  297.  
  298.  
  299.  
  300.  
  301. /*
  302.  *  --   Enable and disable thread execution tracing.  Allow the user to
  303.  *       specify an output file.
  304.  */
  305.  
  306. void 
  307. pcthread_enable_trace_np( char *filename );
  308.  
  309. void 
  310. pcthread_disable_trace_np( void );
  311.  
  312. /*
  313.  *  --   Thread cancellation services
  314.  */
  315.  
  316. int 
  317. pcthread_cancel( pcthread_t th_handle );
  318.  
  319. void 
  320. pcthread_testcancel( void );
  321.  
  322. int 
  323. pthread_setcancel( int cancelability );
  324.  
  325. /*
  326.  *  -- Allow the user to use her own thread-specific cleanup routines
  327.  */
  328.  
  329. void 
  330. pcthread_handler_install_np( pcthread_handler_t handler,
  331.                              pcthread_addr_t argument );
  332.                              
  333. void 
  334. pcthread_handler_remove_np( pcthread_handler_t handler );
  335.  
  336. /*
  337.  *  --   Return the amount of elapsed time since the application began.
  338.  */
  339.  
  340. void 
  341. pcthread_clock_np( timespec_t *time );
  342.  
  343. /*
  344.  *  --   Calculate the expiration time, when given an amount of time to wait.
  345.  */
  346.  
  347. void 
  348. pcthread_get_expiration_np( timespec_t *delta, timespec_t *absolute );
  349.  
  350. /*
  351.  *  --   Check the value of the thread specific errno
  352.  */
  353.  
  354. int 
  355. pcthread_errno_np( void );
  356.  
  357.  
  358.  
  359.  
  360.  
  361. /*
  362.  *  --   Allow client threads to raise an exception.
  363.  */
  364.  
  365. void 
  366. pcthread_exception_raise_np( exception_block_t far *ex, int n );
  367.  
  368. /*
  369.  *  --   Shut down the system gracefully. Client threads should use this
  370.  *       when they CATCH a raised exception (see previous service).
  371.  */
  372.  
  373. void 
  374. pcthread_shutdown_np( char *module_name,
  375.                       char *function_name,
  376.                       char *exception_message,
  377.                       exception_t      exception_code );
  378.  
  379. /*
  380.  *  --   Returns the number of stack words (word = 2 bytes) remaining.
  381.  */
  382.  
  383. int 
  384. pcthread_checkstack_np( char *function_name );
  385.  
  386. /*
  387.  *  --   Thread-safe malloc() and free() routines
  388.  */
  389.  
  390. void * 
  391. pcthread_malloc_np( unsigned block_size );
  392.  
  393. void 
  394. pcthread_deallocate_np( void *ptr );
  395.  
  396. HANDLE
  397. pcthread_window_getinstance_np( void );
  398.  
  399. pcthread_state_t
  400. pcthread_checkstate_np( pcthread_t *th_handle );
  401.  
  402. /*
  403.  *       --   These typedefs are required by the P1003.4a standard and 
  404.  *            relieve the user from the tedium of allocating attributes 
  405.  *            handles at runtime when the client code will be using the 
  406.  *            system's default attributes.
  407.  */
  408.  
  409. #define pcthread_attr_default       (*(pcthread_attr_default_np()))
  410. #define pcthread_mutexattr_default  (*(pcthread_mutexattr_default_np()))
  411. #define pcthread_condattr_default   (*(pcthread_condattr_default_np()))
  412.  
  413. #endif
  414.